数据库错误码说明 - SqliteErrorCodes

概述

以下数据库接口在失败时返回负数，其绝对值即为错误码，与 GetLastError() 返回值一致：

• 连接类：CreateDatabase / OpenDatabase / OpenMemoryDatabase / CloseDatabase
• 改密类：ChangeDatabasePassword / ChangeDatabasePasswordFromPtr
• 执行类：ExecuteSql / ExecuteReader

成功时：

• 连接 / ExecuteReader：返回 大于 0 的句柄
• ExecuteSql / CloseDatabase / 改密接口：返回 1

失败时建议同时调用：

• GetLastError()：获取错误码（正整数，如 7003）
• GetLastErrorString()：获取中文说明（用完后 FreeStringPtr 释放）
• GetDatabaseError(db)：获取 SQLite 引擎侧错误文本（连接已打开时）

long db = ola.OpenDatabase("data/app.db", "");
if (db <= 0) {
    int err = GetLastError();              // 例如 7003
    int code = db < 0 ? (int)(-db) : err;  // 与 GetLastError 一致
    char* msg = (char*)GetLastErrorString();
    // 根据 code 排查，见下表
    FreeStringPtr((int64_t)msg);
} else {
    int ret = ola.ExecuteSql(db, "CREATE TABLE IF NOT EXISTS t(id INTEGER)");
    if (ret != 1) {
        // ret 为负错误码，如 -7008
    }
    ola.CloseDatabase(db);
}

重要：判断连接是否成功请使用 db > 0，不要再用 db != 0（失败时返回负错误码，!= 0 会误判为成功）。

通用错误（10xx）

返回值	GetLastError	说明	排查建议
-1001	1001	权限不足 / 未登录	调用 Login/Reg；检查 FeatureList 含 Sqlite
-1003	1003	参数无效	instance 无效等

数据库错误（70xx）

返回值	GetLastError	说明	排查建议
-7001	7001	数据库参数无效	路径为空、内存地址/大小非法等
-7002	7002	数据库文件已存在	CreateDatabase 不会覆盖；改用 OpenDatabase
-7003	7003	数据库文件不存在	先 CreateDatabase 或检查路径
-7004	7004	打开数据库失败	路径权限、文件损坏、进程占用
-7005	7005	密码错误或密钥校验失败	检查 password / SQLCipher 密钥
-7006	7006	内建表初始化失败	查看日志中 InitOlaDatabase / 迁移错误
-7007	7007	无效的数据库或结果集句柄	是否已 Close / Finalize；db 传 0 时是否已设默认库
-7008	7008	执行 SQL 失败	语法、约束、表名；可看 GetLastErrorString
-7009	7009	SQL 预处理失败	ExecuteReader / ExecuteScalar 的 SQL 非法
-7010	7010	内存库分配或反序列化失败	缓冲区大小、内存数据是否为有效 SQLite 镜像
-7011	7011	修改数据库密码失败	旧密码、磁盘权限、导出/rekey 过程
-7012	7012	关闭数据库失败	是否仍有未 Finalize 的 stmt
-7099	7099	数据库操作内部异常	联系支持并提供日志
-9999	9999	未知错误	查看日志

相关接口

接口	说明
CreateDatabase	创建库文件
OpenDatabase	打开已有库
OpenMemoryDatabase	内存库
ExecuteSql	执行非查询 SQL
GetLastError	读取错误码
GetLastErrorString	读取错误说明